home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_200 / 298_01 / curses.doc < prev    next >
Text File  |  1988-08-15  |  58KB  |  1,473 lines
  1.  
  2.  
  3.    
  4.                        The PC Curses Library 
  5.  
  6.  
  7.  
  8.       (C) Copyright 1987,1988 Jeffrey S. Dean. All Rights Reserved. 
  9.  
  10.  
  11.                     PC CURSES LICENSE AGREEMENT      
  12.    
  13.    The PC Curses Library Package is a copyrighted software 
  14.    package that is being distributed as shareware.  It is NOT in 
  15.    the public domain. By using or distributing this package, you 
  16.    agree to the conditions presented below: 
  17.  
  18.    (1) You may use the PC Curses Library for your own personal 
  19.    use; if you find it useful, you are requested to pay a $20 
  20.    registration fee.  If you are using PC Curses in a 
  21.    commercial, professional, or governmental organization, you 
  22.    are granted a limited license, valid for thirty days, to use 
  23.    this package for evaluation purposes only; if you continue to 
  24.    use this package, you must pay the registration fee.  The 
  25.    registration fee entitles you to use the PC Curses library on 
  26.    one machine.  It also includes one free upgrade. 
  27.  
  28.    (2) Source code is available to registered users only.  
  29.    Source code is also copyrighted, and may NOT be freely copied 
  30.    or distributed.  The price of the source distribution is $20; 
  31.    in addition to the source modules, it include makefiles (as 
  32.    well as a version of the "make" program and other utilities). 
  33.    
  34.    (3) The PC Curses Library (except source) may be freely 
  35.    distributed and copied inside the U.S.; however, you may not 
  36.    charge anything for the distribution.  The distribution must 
  37.    include everything in the original distribution, including 
  38.    this agreement.  You may not distribute this system with any 
  39.    modifications (this includes documentation as well as 
  40.    programs); additions must be placed in separate files and 
  41.    must be clearly marked as such. 
  42.    
  43.    (4) If any part of the PC Curses Library is used in a 
  44.    program, system, or service that is distributed to machines 
  45.    other than the one originally licensed, there is a nominal 
  46.    fee (in addition to the registration fee) and a simple 
  47.    licensing agreement that must be completed.   This fee may be 
  48.    waived if the program or system is distributed as shareware 
  49.    or by a non-profit organization (but the licensing agreement 
  50.    must still be completed).  There are no royalties. 
  51.  
  52.  
  53.    (5) DISCLAIMER OF WARRANTY: THE PC CURSES PACKAGE IS SOLD "AS 
  54.    IS" AND WITHOUT ANY WARRANTIES, EXPRESS OR IMPLIED, AS TO 
  55.    PERFORMANCE OR MERCHANTABILITY.  BECAUSE OF THE DIVERSITY OF 
  56.    CONDITIONS UNDER WHICH THIS PACKAGE MAY BE USED, NO WARRANTY 
  57.    OF FITNESS FOR A PARTICULAR PURPOSE IS OFFERED.  THE USER IS 
  58.    ADVISED TO TEST THE PACKAGE THOROUGHLY BEFORE RELYING ON IT.  
  59.    THE USER MUST ASSUME FULL RISK AS TO THE RESULTS AND 
  60.    PERFORMANCE OF USING THE PACKAGE.  ANY LIABILITY OF THE 
  61.    AUTHOR OR DISTRIBUTOR WILL BE LIMITED EXCLUSIVELY TO PRODUCT 
  62.    REPLACEMENT.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY 
  63.    DAMAGES ARISING FROM THE USE OR INABILITY TO USE THIS 
  64.    PACKAGE.       
  65.        
  66.  
  67.                          Ordering PC Curses 
  68.    
  69.    PC Curses complete evaluation system . . .  $5  
  70.    PC Curses registration . . . . . . . . . .  $20
  71.  
  72.    The following items are available only to registered users:
  73.  
  74.    PC Curses source code . . . . . . . . . . . $20
  75.    PC Curses redistribution license . . . . .  $20
  76.  
  77.    When ordering source code, please specify the compiler 
  78.    (Microsoft or Turbo) and version you are using. 
  79.  
  80.    All payments must be in U.S. dollars.  For orders outside the 
  81.    U.S., please add an extra $15 per order.  (The evaluation 
  82.    system is not available outside the U.S.) 
  83.  
  84.    Send orders and other correspondence to:
  85.    
  86.                Jeff Dean
  87.                710 Chimalus
  88.                Palo Alto, CA  94306 
  89.    
  90.     
  91.                          Table of Contents
  92.    
  93.    Introduction 
  94.    Programmers Notes 
  95.    Standard Curses Functions
  96.    Terminfo Curses Functions
  97.    Even Newer Curses Functions
  98.    Special PC Curses Functions
  99.    Special PC-Specific Functions
  100.    Tracing in PC Curses 
  101.    What's Different
  102.    Version History 
  103.     
  104.  
  105. INTRODUCTION 
  106.  
  107.  
  108.    PC Curses is a C Library designed to provide compatibility   
  109.    with the Unix curses package.  It was written for applications 
  110.    running on IBM PC compatible computers developed under 
  111.    Microsoft C or Turbo C. 
  112.  
  113.    The Unix curses package was originally developed at the 
  114.    University of California at Berkeley as a screen management 
  115.    and windowing package, providing various tools for creating 
  116.    and manipulating windows.  Its key strength is the ability to 
  117.    deal with many different types of terminals at any line speed 
  118.    in a semi-optimized fashion.  For many years, it was the only 
  119.    generally available package that provided windowing 
  120.    capabilities in the Unix environment. 
  121.    
  122.    PC Curses was produced to aid in porting programs from MS-DOS 
  123.    to Unix, though it is also useful in writing MS-DOS software 
  124.    that may need to be ported to Unix. The PC environment is 
  125.    drastically different from Unix, so while this package is 
  126.    meant to be functionally similar to the Unix one, there are a 
  127.    few small differences externally (but many differences 
  128.    internally). 
  129.    
  130.    This package is much simpler that the Unix version.  Because 
  131.    of the nature of the PC environment, there is no need for 
  132.    anything like cursor motion optimization.  Because of the 
  133.    high screen bandwidth, little effort is spent trying to 
  134.    optimize screen output.  Because the PC has features not 
  135.    always available in other environments, additional routines 
  136.    (not in the original curses package) are provided. 
  137.  
  138.    The PC Curses code was developed independently, without 
  139.    reference to the Unix source code.  This documentation is 
  140.    based on experience with the curses package, on Ken Arnold's 
  141.    paper "Screen Updating and Cursor Movement Optimization: A 
  142.    Library Package," and on the Unix System V curses 
  143.    documentation. 
  144.  
  145.    Arnold's paper (or the newer System V documentation) should 
  146.    be considered required reading in order to understand how 
  147.    this system works.  The documentation included here 
  148.    summarizes some of the relevant information, and points out 
  149.    differences between the Unix version and the PC version. 
  150.                 
  151.    Note that there are two major versions of curses.  The 
  152.    original, produced some time ago at UC Berkeley, used the 
  153.    termcap database.  More recently, the termcap (or termlib) 
  154.    database has been recast into the terminfo database, for 
  155.    efficiency and extensions.  A new version of curses was 
  156.    written to take advantage of this system.  PC Curses derives 
  157.    primarily from the earlier version, with some features of the 
  158.    later version added.  In this documentation, the newer 
  159.    version is referred to as "terminfo curses"; elsewhere, you 
  160.    may hear it referred to as "System V curses." 
  161.  
  162.    Please let us know what you think of this package; any 
  163.    feedback, positive or negative, is appreciated.  If you have 
  164.    any suggestions, problems, or code you would like to see 
  165.    included in the distribution, please contact us.  We are 
  166.    planning to continue to improve and expand this package,  
  167.    adding subroutines, utilities, and anything else that would 
  168.    prove generally useful to curses programmers. 
  169.  
  170.  
  171. PROGRAMMERS NOTES 
  172.  
  173.    The basic "unit" of manipulation in curses is a window.  
  174.    Windows are dynamically allocated structures, and are passed 
  175.    around by pointer. Windows represent a rectangular region on 
  176.    the terminal screen. 
  177.  
  178.    The windows are, in a sense, buffered.  There are a variety 
  179.    of operations for writing windows, but no changes visibly 
  180.    take place until a wrefresh() command is issued.  At this 
  181.    point, all the changes are written to the physical screen. 
  182.  
  183.    There are two special windows in the system, created on 
  184.    startup.  One is the current screen (curscr), and represents 
  185.    the information that is presently on the screen.  The other 
  186.    is the standard sc